CKM_AES_GCM
This section provides a summary of CKM_AES_GCM.
Note
This section describes the behavior of CKM_AES_GCM from ProtectToolkit 7.1.0 onwards. In ProtectToolkit 7.0.0, CKM_AES GCM behaves identically to CKM_AES_GCM_OLD.
-
When using ProtectToolkit 7.1.0 or newer, refer to the description of CKM_AES_GCM shown below. For information about this mechanism's compatibility with ProtectToolkit 7.0.0 applications, refer to Compatibility with ProtectToolkit 7.0.0 Applications.
-
When using ProtectToolkit 7.0.0, refer to the description of CKM_AES_GCM_OLD. For more information, refer to CKM_AES_GCM_OLD.
Supported operations
| Operation | Support |
|---|---|
| Encrypt and Decrypt | Yes (Single-part operation only) |
| Sign and Verify | No |
| SignRecover and VerifyRecover | No |
| Digest | No |
| Generate Key/Key-Pair | No |
| Wrap and Unwrap | Yes |
| Derive | No |
FIPS Mode support
| Available in FIPS Mode | Restrictions in FIPS Mode |
|---|---|
| Yes | User specified IV not allowed when performing encryption or wrapping |
Key size range (bytes) and parameters
| Key size minimum/maximum | Value |
|---|---|
| Minimum | 16 |
| FIPS Minimum | 16 |
| Maximum | 32 |
Parameter
CK_GCM_PARAMS
Mechanism description
For a full description of this mechanism, refer to the PKCS#11 version 2.40 documentation from RSA Laboratories.
AES GCM is a single part encrypt/decrypt operation; the following sequence of PKCS#11 function calls can be used in applications:
C_EncryptInit(...)
C_Encrypt(...)
...
C_DecryptInit(...)
C_Decrypt(...)
C_EncryptInit() optionally returns a randomly generated IV.
C_Encrypt() returns the ciphertext and tag.
When encrypting or decrypting, the caller must specify an IV using the pIV and ulIvLen fields of CK_GCM_PARAMS. Passing NULL as the IV returns an error.
When encrypting, the caller may set the value of the IV to all zeros. If the caller sets the value of the IV to all zeros, the HSM will generate the same number of random bytes to use as the IV. When the encryption completes, the IV pointed at by the pIV in the mechanism parameter is updated with the new IV.
With FIPS Mode enabled, an error is returned from C_EncryptInit if the IV specified is not all zero; that is, random IV values must be used.
The PTK implementation of AES GCM assumes the following limitations:
-
IV maximum length is 128 octets (max value from NIST test vectors).
-
AAD maximum length is 32768 octets.
-
ulTagBits must be >= 32 or <= 128 and a multiple of 8. If “FIPS Alg Only” then value must be 128, 120, 112, 104 or 96.
-
Message maximum length is 63KB - ulAADLen octets.
Compatibility with ProtectToolkit 7.0.0 applications
Prior to ProtectToolkit 7.1.0, CKM_AES_GCM would always return the IV appended to the output. From ProtectToolkit 7.1.0 onwards, the IV is returned in the mechanism parameter during the C_EncryptInit call.
Applications designed for and expecting the old behavior should call the CKM_AES_GCM_OLD mechanism. For more information, refer to CKM_AES_GCM_OLD.
If you cannot change the application, the ET_PTKC_GENERAL_LEGACY_GCM configuration item can be used. Legacy applications that are written to call the CKM_AES_GCM mechanism but expect to see CKM_AES_GCM_OLD behavior should set this configuration value. For more information about this configuration item, refer to ProtectToolkit-C mechanism configuration items.
Example:
$ export ET_PTKC_GENERAL_LEGACY_GCM=YES
Return to ProtectToolkit-C mechanisms.
